--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type"
+ content="text/html; charset=ISO-8859-1">
+ <title>Xen Configuration Syntax</title>
+</head>
+<body>
+<center>
+<h1>Xen Configuration Syntax</h1>
+<br>
+Version 0.1<br>2004 June 21<br>
+</center>
+
+<h1>Xen Configuration</h1>
+The Xen virtual machine creation tools provide command-line interfaces and
+HTTP interfaces to creating virtual machines. Underneath all these interfaces
+virtual machine configuration data is represented in a common configuration syntax
+called SXP.
+
+The SXP syntax is s-expressions (sxprs), a simple bracketed abstract syntax.
+Python lists are used to represent its parsed form, with a support
+api providing access to fields and values (class xenmgr.sxp).
+
+<h1>SXP syntax</h1>
+<p>A general s-expression has the syntax:
+<code><pre>
+s-exp = '(' s-exp* ')' | atom | string
+</pre></code>
+Where an <code>atom</code> is an unquoted string, such as fred or /domain/0.
+A <code>string</code> is a quoted string, supporting the usual escape sequences.
+Strings support single or double quotes: 'fred 1' or "fred 2" are both accepted.
+The characters ()[]<>{} are separators.
+
+<p>An <code>element</code> is an s-expression representing data similar to XML.
+It has the form:
+<code><pre>
+element = '(' name attributes? value* ')'
+name = atom
+attributes = '(' '@' attribute* ')'
+attribute = '(' attrname attrval ')'
+attrname = atom
+attrval = atom | string
+value = element | atom | string
+</pre></code>
+The <code>name</code> is the element name (roughly indentifying its type).
+The <code>attributes</code> is a list of attribute-values.
+We usually prefer to avoid using attributes, and use sub-elements instead.
+As in XML, any element may have the attribute <code>id</code> to give it an identifier
+for later reference.
+
+<h1>VM configuration</h1>
+A vm configuration is a single SXP vm element, with subelements for
+vm parameters and devices. The supported elements and their fields
+are listed below.
+
+<h2>(vm) element</h2>
+The top-level element, a virtual machine configuration.
+<ul>
+ <li>name: string, required. Domain name.
+ <li>id: int, optional, default generated. Domain unique id.
+ <li>memory: int, optional, default 128. Domain memory in MB.
+ <li>image: linux | netbsd | ..., required. Domain image (OS-specific element).
+ <li>controller: any device controller type, optional, default none.
+ <li>device: any device type, optional, repeats. Device.
+ <li>auto-restart: bool, optional, default false. Auto-restart flag.
+</ul>
+
+<h2>(image (linux)) element</h2>
+Defines a linux kernel image and its command-line parameters.
+<ul>
+ <li>kernel: string, required. Kernel image file (absolute path).
+ <li>root: string, optional. Root device.
+ <li>ip: string, optional. IP address specifier.
+ <li>ramdisk: string, optional, default none. Ramdisk file (absolute path).
+ <li>args: string, optional. Extra kernel args.
+</ul>
+
+<h2>(image (netbsd)) element</h2>
+Defines a netbsd kernel image and its command-line parameters.
+<ul>
+ <li>kernel: string, required. Kernel image file.
+ <li>root: string, optional. Root device.
+ <li>ip: string, optional. IP address specifier.
+ <li>ramdisk: string, optional, default none. Ramdisk file.
+ <li>args: string, optional. Extra kernel args.
+</ul>
+
+<h2>(controller (block)) element</h2>
+Define that the vm is a block device controller backend.
+The vm can have pci devices configured, but no virtual
+block devices.
+
+<h2>(controller (net)) element</h2>
+Define that the vm is a net device controller backend.
+The domain may not have virtual network interfaces (vifs) configured.
+
+<h2>(device (vif)) element</h2>
+Defines a virtual network interface.
+<ul>
+ <li>mac: string, optional, default generated. Interface MAC address.
+ <li>quota info: optional. Subelements bytes and usecs.
+ <li>bridge: string, optional, default system-dependent. Bridge to connect to.
+</ul>
+A random MAC is assined is not specified.
+The interface is connected to the system default bridge if no bridge
+is specified.
+
+<h2>(device (vbd)) element</h2>
+Defines a virtual block device.
+<ul>
+ <li>uname: string, required. Virtual block device id, e.g phys:hda1.
+ <li>dev: string, required. Device file name in domain, e.g. xda1.
+ <li>mode: string, optional, default r. Read-write mode: r | rw | w.
+</ul>
+The uname field defines the device being exported from the block device
+controller. The dev field defines the device name the vm will see.
+The device is read-only unless the mode contains w.
+
+<h2>(device (pci)) element</h2>
+Defines a pci device.
+<ul>
+ <li>bus: int, required. PCI bus id.
+ <li>dev: int, required. PCI dev id.
+ <li>func: int, required. PCI func id.
+</ul>
+The bus, dev or func may be given in hex,
+e.g. 0xff. With no leading 0x they are interpreted as decimal.
+
+<h2>(vnet) element</h2>
+Defines the virtual networks associated with vifs (may go away soon).
+Contains a list of vif elements:
+<ul>
+ <li>id: id of the vif being configured.
+ <li>vnet: id of vnet the vif is assigned to.
+</ul>
+
+<h2>(vfr) element</h2>
+Defines the ip addresses for vifs (may go away soon).
+Contains a list of vif elements:
+<ul>
+ <li>id: vif index
+ <li>ip: vif ip address
+</ul>
+
+<h1>Examples</h1>
+<p> A vm with 64 MB memory, root on /dev/xda1 (mapped from /dev/hda1),
+one vif with default MAC.
+<code><pre>
+(vm
+ (name xendom1)
+ (memory 64)
+ (image
+ (linux
+ (kernel /boot/vmlinuz-2.4.26-xen)
+ (ip ::::xendom1:eth0:dhcp)
+ (root /dev/xda1)
+ (args 'rw fastboot 4')
+ )
+ )
+ (device (vif))
+ (device (vbd (uname phy:hda1) (dev xda1) (mode w)))
+)
+</pre></code>
+
+<p>A vm with 64 MB memory, NFS root, and 2 vifs on separate vnets.
+<code><pre>
+(vm
+ (name xendom2)
+ (memory 64)
+ # Define a linux image.
+ (image
+ (linux
+ (kernel "/boot/vmlinuz-2.4.26-xen")
+ (ip "::::xendom2:eth0:dhcp")
+ (root "/dev/nfs")
+ (args "rw fastboot nfsroot=15.144.25.79:/opt/xen/xendom2 4")
+ )
+ )
+ # Define some vifs, with ids for use later.
+ (device (vif (@ (id vif1)) (mac aa:00:00:00:00:12)))
+ (device (vif (@ (id vif2)) (mac aa:00:00:00:10:12)))
+
+ # Configure vnets. Refer to vifs by id.
+ (vnet (vif (id vif1) (vnet 1))
+ (vif (id vif2) (vnet 2)))
+
+)
+</pre></code>
+
+</body>
+</html>
projects / xen.git / commitdiff